docs: Update docs/README.md and Hugo Relearn to 5.23.0 #6251
Conversation
bernhardkaindl
force-pushed
the
docs-update-README-and-hugo-relearn-to-5.23
branch
from
b318cea to
d126e7c
Compare
bernhardkaindl
force-pushed
the
docs-update-README-and-hugo-relearn-to-5.23
branch
from
d126e7c to
31dab81
Compare
Minor updates of the Hugo documentation: - The current Ubuntu snap package of Hugo is not supported by the docs. We should take a first minor step towards fixing this. - `doc/README.md` is outdated and should be updated. It says that the Ubuntu snap of Hugo works, but it does not anymore. Fix this by updating the outdated information. - An initial fix is to update the Relearn theme from 5.20.x to 5.23.0: - It does not introduce breaking changes. - It introduces more straightforward page links and deprecates older syntax. - Fix the warnings by updating relative links accordingly. Signed-off-by: Bernhard Kaindl <bernhard.kaindl@cloud.com>
bernhardkaindl
force-pushed
the
docs-update-README-and-hugo-relearn-to-5.23
branch
from
31dab81 to
458b138
Compare
|
@robhoes Can you review this PR and check if you like to merge it? (Pau and Christian approved it) GitHub tells me that I no longer have write access and therefore cannot merge anymore. |
Signed-off-by: Bernhard Kaindl <bernhard.kaindl@cloud.com>
There was a problem hiding this comment.
When updating to newer versions of the Hugo Relearn theme,
Hugo/Relearn warned about a few broken links.
The broken links are currently live on https://xapi-project.github.io/new-docs/,
and I tested the fixes on top of this PR. This comment gives the details about the new commit to
Fix currently broken links to toolstack/features: HA, snapshots:
The cause is simple:
The old docs site had the features at /features/HA/HA.html and /features/snapshots/snapshots.html.
But on the new-docs site, they are below toolstack/features
Fix them to target the respective new-docs pages toolstack/features/HA and toolstack/features/snapshots, respectively.
The fixes are kept as relative links, so all of them are work in 3 environments:
- In the fast Markdown review renderer in VS Code / Codium and its derivatives.
- The local
hugo serverrenderer - Deployment using GitHub Pages at different URLs.
Sample locations of the currently broken links for review:
- https://xapi-project.github.io/new-docs/design/multiple-cluster-managers/:
- two times to xhad (broken link):
- On the top of the page: "Xapi currently uses a cluster manager called xhad."
- On the bottom of the page: "conform to the exact same interface as xhad."
Fixes for review at: https://xenserver-next.github.io/xen-api/design/multiple-cluster-managers/ (working links)
- two times to xhad (broken link):
Fix 3: Link from design/ocfs2 to (toolstack)/features/HA:
Old: https://xapi-project.github.io/new-docs/design/ocfs2:
- "which provides Host-level High Availability." (using
../../.., it traverses to the top-level above the/new-docs, where the user ends up on the old docs site at https://xapi-project.github.io/features/HA/HA.html
New: https://xenserver-next.github.io/xen-api/design/ocfs2 (fix for review):
- "which provides Host-level High Availability." (links to the correct page within the new docs site)
Fix 4: "Read more about Snapshots: the High-Level Feature." at on top of this page:
Old: https://xapi-project.github.io/new-docs/xen-api/topics/snapshots/ (link results in 404)
New: https://xenserver-next.github.io/xen-api/xen-api/topics/snapshots/ (review of the fixed link)
PS: I would have merged it already before this commit, but I lost the write permission needed for the merge.
Signed-off-by: Bernhard Kaindl <bernhard.kaindl@cloud.com>
Minor updates of the Hugo documentation:
The current Ubuntu
snappackage of Hugo is not supported by the docs.We should take a first minor step towards fixing this.
doc/README.mdis outdated and should be updated (new version).It says that the Ubuntu snap of Hugo works, but it does not anymore.
Fix this by updating the outdated information.
An initial fix is to update the Relearn theme from 5.20.x to 5.23.0:
A preview is available on my site: https://xenserver-next.github.io/xen-api/index.html